Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
adding the frame
When a new frame is created, it automatically connects itself to its part as one of its display frames. This ensures that frames are always valid and usable. There is no extra work the object which creates the new frame need do besides create the frame itself.
On the other side of the process, the part being displayed must respond to the call to add the new display frame:
void DisplayFrameAdded(in ODFrame* frame)
There are probably a number of things the part must do in response to gaining a new display frame. Most of these things will depend on the nature and implementation of the part itself; what these might be are left as an exercise for the reader. However, there are a few general actions a part should take:
• Add the new display frame to the part’s list of its display frames. This list, like the part’s other internal structures, is completely hidden from OpenDoc. The developer may represent this list any way he chooses. The simplest of parts may be able to do without such a list, but most parts will require it.
• Validate the viewType and presentation of the new frame. The part must support the required set of view types. Other kinds of view types or presentations are optional. The part should inspect these values and correct them if necessary. See the recipe for View Types and Presentations for more detail.
• Add partInfo to the frame. The partInfo field of a frame is a convenient place for a part to store information about that view of itself. It can be anything from a simple ID to a pointer to a complicated structure or a helper object. The partInfo for a frame is stored in the storage unit for the frame, not the part. If the part has many frames of which only a few are internalized, only the partInfo of those frames will be internalized and take up memory.
• If the frame being added is a root frame, the part may want to activate that frame. See the recipe on Activation for more information on how to do that.
• Do not try to negotiate with the containing part for a different frame shape. The call to CreateFrame has not returned yet, so the containing part has not had a chance to add the new frame to its contents. Unless the containing part is very clever, it will not be able to negotiate a new shape for the frame at this point. It's better to wait until the embedded part's first time receiving a FacetAdded call.
synchronizing with a source frame
Parts may have multiple display frames. Sometimes, two or more views of a part must be synchronized. This is necessary to allow the part to update one frame when editing has taken place in another. In many cases, a part can determine these dependencies internally. But there are some cases when parts need to be synchronized externally.
A typical situation where frames should be synchronized occurs when the user opens a window view of an embedded frame. The embedded part’s Open() method is called, wherein it will create the new window. The new window will have a root frame which will be added as a display frame of the part. Now, since the part is in control of this process, it already knows that it must keep these two views synchronized. However, if the part has any embedded parts, they won’t know that the new display frames added to them should be synchronized with other frames. So the root part of the new window should use AttachSourceFrame() to do that.
The part being displayed should take whatever action necessary to synchronize the frames. As a minimum, if the two frames are the same kind of presentation, it should duplicate embedded frames in one frame into the other.
